<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Running Ibator With Maven</title>
  <link type="text/css" rel="stylesheet" href="../ibator.css"/>
</head>
<body>

<div class="menuNav">
  <p>
    <a href="../index.html" target="_top">Show Menu</a>
    <a href="runningWithMaven.html" target="_top">Hide Menu</a>
  </p>
</div>

<h1>Running Ibator With Maven</h1>
<p>Ibator includes a Maven plugin for integration into a maven build.  In
keeping with Maven's configuration by convention strategy, including Ibator
in a Maven build can be very simple.  The minimum configuration is shown below:</p>

<pre>
   &lt;project ...&gt;
     ...
     &lt;build&gt;
       ...
       &lt;plugins&gt;
        ...
        &lt;plugin&gt;
      	  &lt;groupId&gt;org.apache.ibatis.ibator&lt;/groupId&gt;
      	  &lt;artifactId&gt;ibator-maven-plugin&lt;/artifactId&gt;
          &lt;version&gt;1.2.2&lt;/version&gt;
        &lt;/plugin&gt;
        ...
      &lt;/plugins&gt;
      ...
    &lt;/build&gt;
    ...
  &lt;/project&gt;

</pre>

<p>Of course, things are never that easy!  </p>

<h2>Maven Goal and Execution</h2>
<p>The Ibator Maven plugin includes one goal:</p>
<ul>
  <li><code>ibator:generate</code></li>
</ul>
<p>The goal is not automatically executed by Maven.  It can be executed in two
ways.</p>
<p>The goal can be executed from the command line with the command:</p>
<ul>
  <li><code>mvn ibator:generate</code></li>
</ul>
<p>You can pass parameters to the goal with standard Maven command line properties.
For example:</p>
<ul>
  <li><code>mvn -Dibator.overwrite=true ibator:generate</code></li>
</ul>
<p>This will run Ibator and instruct Ibator to overwrite any existing Java files
it may find.</p>
<p>In a continuous build environment, you may want to automatically execute
Ibator as a part of a Maven build.  This can be accomplished by configuring
the goal to execute automatically.  An example of this is shown below:</p>
<pre>
   &lt;project ...&gt;
     ...
     &lt;build&gt;
       ...
       &lt;plugins&gt;
        ...
        &lt;plugin&gt;
      	  &lt;groupId&gt;org.apache.ibatis.ibator&lt;/groupId&gt;
      	  &lt;artifactId&gt;ibator-maven-plugin&lt;/artifactId&gt;
          &lt;version&gt;1.2.2&lt;/version&gt;
          &lt;executions&gt;
            &lt;execution&gt;
              &lt;id>Generate iBATIS Artifacts&lt;/id&gt;
              &lt;goals&gt;
                &lt;goal>generate&lt;/goal&gt;
              &lt;/goals&gt;
            &lt;/execution&gt;
          &lt;/executions&gt;
        &lt;/plugin&gt;
        ...
      &lt;/plugins&gt;
      ...
    &lt;/build&gt;
    ...
  &lt;/project&gt;

</pre>
<p>The Ibator plugin is bound to the <code>generate-sources</code> phase of a
Maven build, so it will execute before the complie step.  Also note that
Ibator generates both Java source files and XML resources.  The Ibator goal
will bind both generated Java files and XML resources to the build and they
will both be included in any JAR generated by the build.</p>

<h2>Ibator Configuration Properties</h2>
<p>Any property specified in the POM will be passed into the Ibator configuration
file and may be used in the normal way.  For example:</p>
<pre>
   &lt;project ...&gt;
     ...
     &lt;properties&gt;
       &lt;dao.target.dir&gt;src/main/java&lt;/dao.target.dir&gt;
     &lt;/properties&gt;
     ...
     &lt;build&gt;
       ...
       &lt;plugins&gt;
        ...
        &lt;plugin&gt;
      	  &lt;groupId&gt;org.apache.ibatis.ibator&lt;/groupId&gt;
      	  &lt;artifactId&gt;ibator-maven-plugin&lt;/artifactId&gt;
          &lt;version&gt;1.2.2&lt;/version&gt;
          &lt;executions&gt;
            &lt;execution&gt;
              &lt;id>Generate iBATIS Artifacts&lt;/id&gt;
              &lt;goals&gt;
                &lt;goal>generate&lt;/goal&gt;
              &lt;/goals&gt;
            &lt;/execution&gt;
          &lt;/executions&gt;
        &lt;/plugin&gt;
        ...
      &lt;/plugins&gt;
      ...
    &lt;/build&gt;
    ...
  &lt;/project&gt;

</pre>
<p>In this case, the property may be accessed in the Ibator configuration file with the
syntax <code>${dao.target.dir}</code>.

<h2>Parameter Reference</h2>
<p>All parameters are optional and have suitable defaults.</p>
<table cellspacing="0" cellpadding="5" border="1">
  <tr>
    <th>Parameter</th>
    <th>Expression</th>
    <th>Type</th>
    <th>Comments</th>
  <tr>
  <tr>
    <td valign="top">configurationFile</td>
    <td valign="top">${ibator.configurationFile}</td>
    <td valign="top">java.io.File</td>
    <td valign="top">The location of the Ibator configuration file.
      <p>Default value:</p>
      ${basedir}/src/main/resources/ibatorConfig.xml
    </td>
  </tr>
  <tr>
    <td valign="top">contexts</td>
    <td valign="top">${ibator.contexts}</td>
    <td valign="top">java.lang.String</td>
    <td valign="top">A comma delimited list of contexts to use in the current run of
      Ibator. Any id specified in the list must exactly match the value of the id
      attribute of an &lt;ibatorContext&gt; configuration element.
      Only ids specified in this list will be active for this run of Ibator.
      If this parameter is not specified, then all contexts will be active.
    </td>
  </tr>
  <tr>
    <td valign="top">jdbcDriver</td>
    <td valign="top">${ibator.jdbcDriver}</td>
    <td valign="top">java.lang.String</td>
    <td valign="top">If you specify a <code>sqlScript</code>, then this is the
      fully qualified JDBC driver class name to use when connecting to the
      database.
    </td>
  </tr>
  <tr>
    <td valign="top">jdbcPassword</td>
    <td valign="top">${ibator.jdbcPassword}</td>
    <td valign="top">java.lang.String</td>
    <td valign="top">If you specify a <code>sqlScript</code>, then this is the
      password to use when connecting to the database.
    </td>
  </tr>
  <tr>
    <td valign="top">jdbcURL</td>
    <td valign="top">${ibator.jdbcURL}</td>
    <td valign="top">java.lang.String</td>
    <td valign="top">If you specify a <code>sqlScript</code>, then this is the
      JDBC URL to use when connecting to the database.
    </td>
  </tr>
  <tr>
    <td valign="top">jdbcUserId</td>
    <td valign="top">${ibator.jdbcUserId}</td>
    <td valign="top">java.lang.String</td>
    <td valign="top">If you specify a <code>sqlScript</code>, then this is the
      JDBC user ID to use when connecting to the database.
    </td>
  </tr>
  <tr>
    <td valign="top">outputDirectory</td>
    <td valign="top">${ibator.outputDirectory}</td>
    <td valign="top">java.io.File</td>
    <td valign="top">The directory where files generated by Ibator will be placed.
      This directory is used whenever a <code>targetProject</code> in the Ibator
      configuration file is set to the special value "MAVEN" (case sensitive).
      <p>Default value:</p>
      ${project.build.directory}/generated-sources/ibator
    </td>
  </tr>
  <tr>
    <td valign="top">overwrite</td>
    <td valign="top">${ibator.overwrite}</td>
    <td valign="top">boolean</td>
    <td valign="top">If true, then existing Java files will be overwritten if an
      existing Java file if found with the same name as a generated file. If not
      specified, and a Java file already exists with the same name as a generated
      file, then Ibator will write the newly generated Java file to the proper
      directory with a unique name (e.g. MyClass.java.1, MyClass.java.2, etc.).
      <b>Important: Ibator will always merge and overwrite XML files.</b>
      <p>Default value:</p>
      false
    </td>
  </tr>
  <tr>
    <td valign="top">sqlScript</td>
    <td valign="top">${ibator.sqlScript}</td>
    <td valign="top">java.io.File</td>
    <td valign="top">Location of a SQL script file to run before generating code.
     If null, then no script will be run.  If not null, then <code>jdbcDriver</code>,
     <code>jdbcURL</code> must be supplied also.  In addition,
     <code>jdbcUserId<code> and <code>jdbcPassword</code> may be supplied if
     the database requires authentication.
    </td>
  </tr>
  <tr>
    <td valign="top">tableNames</td>
    <td valign="top">${ibator.tableNames}</td>
    <td valign="top">java.lang.String</td>
    <td valign="top">If specified, then this is a comma delimited list of tables to
      use in the current run of Ibator. Any table specified in the list must exactly
      match the fully qualified table name specified in a &lt;table&gt; configuration
      element. Only tables specified in this list will be active for this run of
      Ibator. If this argument is not specified, then all tables will be active.
      Specify table names as:
      <p><code>table<br/>
      schema.table<br/>
      catalog..table<br/>
      etc.</code></p>
    </td>
  </tr>
  <tr>
    <td valign="top">verbose</td>
    <td valign="top">${ibator.verbose}</td>
    <td valign="top">boolean</td>
    <td valign="top">If true, then Ibator will write progress messages to the
      build log.
    </td>
  </tr>
</table>

<h2>Interpretation of targetProject</h2>
<p>The <code>targetProject</code> attribute of the generator configurations is interpreted
differently when running with Maven.  If set to the special value "MAVEN" (case
sensitive), then <code>targetProject</code> will be set to the plugin's output directory,
and that directory will be created if it doesn't already exist.  If not set to "MAVEN", then
<code>targetProject</code> will be interpreted as normal by Ibator - it must be set
to a directory that already exists.</p>
</body>
</html>